Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 012 / newkey.arc / NEWKEY.DOC next >

Wrap

Text File | 1986-10-26 | 41.8 KB | 1,136 lines

NEWKEY A Keyboard Enhancer for The IBM Personal Computer Version 1.1 (C)Copyright Frank A. Bell, 1984 All rights reserved. Frank A. Bell 20950 Smallwood Birmingham, MI 48010 .pa TABLE OF CONTENTS INTRODUCTION ............................................. 1 GETTING STARTED........................................... 2 LOADING NEWKEY.......................................... 2 Newkey Parameters..................................... 2 DEFINING A KEY.......................................... 3 Space Considerations.................................. 3 Backspace Handling.................................... 4 SPECIAL KEY DEFINITION FEATURES........................... 4 NESTED KEY TRANSLATION.................................. 4 Recursion............................................. 4 TRANSLATION BYPASS...................................... 5 VARIABLE LENGTH FILL-IN-THE-BLANKS...................... 5 FIXED LENGTH FILL-IN-THE-BLANKS......................... 6 SPECIAL FEATURES.......................................... 7 SWITCHING NEWKEY OFF/ON................................. 7 TRANSLATION BYPASS...................................... 7 NEWKEY1 OVERVIEW.......................................... 8 INVOKING NEWKEY1........................................ 8 NEWKEY1 FUNCTIONS......................................... 8 DISPLAY DIRECTORY (/d).................................. 8 DISPLAY TRANSLATION OF KEY (/k)......................... 8 SAVE FILE (filename.ext/s).............................. 8 LOAD FILE (filename.ext/l).............................. 9 Special note to DOS 2.0 users......................... 9 MERGE FILE (filename.ext/m or filename.ext/m/o).........10 CLEAR CURRENT KEY DEFINITIONS (/c)......................10 SWITCH STATUS (/t)......................................10 UNLOAD AND RECLAIM MEMORY (DOS 1.1 only) (/u)...........10 MODIFYING NEWKEY..........................................11 MODIFICATIONS...........................................11 FIELDS WHICH MAY BE MODIFIED............................12 DESCRIPTION OF KEY TRANSLATION DISPLAY....................13 SAMPLE KEY DEFINITION FILES...............................14 ASM.KEY.................................................14 DVORAK.KEY..............................................14 TEST.KEY................................................14 WS.KEY..................................................15 GENERAL DOS KEYS COMMON TO MOST SAMPLE FILES............16 INFORMATION ABOUT THE FILES ON THE NEWKEY DISK............16 NEWKEY OVERVIEW...........................................17 NEWKEY REQUIREMENTS.....................................17 HOW DOES NEWKEY WORK?...................................17 NEWKEY'S LIMITATIONS....................................17 TIPS ON USING NEWKEY......................................18 USE YOUR AUTOEXEC.BAT FILE..............................18 SETTING THE DYNAMIC DEFINE AREA SIZE PARAMETER..........18 DO NOT FORGET TO SAVE YOUR KEY DEFINITIONS..............18 COMBINING KEY DEFINITION FILES..........................19 MULTIPLE KEY DEFINITION FILES...........................19 DISCLAIMER................................................20 PERMISSION TO COPY........................................20 THE USER-SUPPORTED CONCEPT................................21 PROBLEMS, SUGGESTIONS, ETC................................21 .pa NEWKEY INTRODUCTION PURPOSE The Newkey keyboard enhancer simplifies the entry of common keystroke sequences by allowing these sequences to be assigned to any key desired. Once assigned to a particular key, whenever that key is struck the predefined sequence of keystrokes will be returned in place of the struck key. For example, the alt C key might be defined as 'copy' and whenever alt C is struck the string 'copy' will be returned. Newkey allows customization of software packages, ready creation of boiler plate passages, keyboard redefinition and other useful purposes. Several sample key definition files are included with Newkey and will be described later. Newkey provides many key translation features including: - Ability to define any key - Variable length "pauses" during key translation - Fixed length "pauses" during key translation - Nested key translation - Translation bypass for native entry of defined key - User defined dynamic define area length Newkey1, the Newkey support program, provides many functions including: - Saving key definitions on disk - Loading key definitions from disk - Merging key definitions from disk - Directory display of keys with translations - Individual display of key translations - Newkey on/off switch - Clear current key definitions - Unload and reclaim memory (DOS 1.1 only) .pa GETTING STARTED LOADING NEWKEY To load newkey type newkey [/parameters] and press the enter key. Within a second or two a full screen will be displayed with the message; NEWKEY loaded at the bottom. When you have received this message Newkey has been loaded. At this stage Newkey is ready to use. You may wish to load a predefined set of key translations. To do this refer to the 'Load File' section. Newkey Parameters (optional) Function: Change dynamic define area length. Newkey comes with a default dynamic define area length which will accept up to 300 characters of new key definitions. This default may be changed at run time by specifying the parameter '/xxxxx' when first invoking Newkey. 'xxxxx' is up to a 5 digit number specifying the number of characters which Newkey will reserve for the dynamic define area. Newkey will reserve twice this number of bytes in memory (each character requires two bytes). For example: newkey /500 will reserve enough space for 500 characters of translation (1000 bytes of storage.) This parameter is especially valuable to DOS 2.0 users as described in the 'LOAD FILE' section in the 'NEWKEY1 OVERVIEW'. The legal range for this number is 5 - 13,500. .pa DEFINING A KEY To define a key follow these steps: 1. Press the alt = key. This will cause the cursor to take on a block shape. As long as you are in key definition mode the cursor will retain some sort of block shape. 2. Press the key you wish to define. Although it will appear to you as if nothing has happened, Newkey will assume that this is the key to be defined. 3. Now enter the keystrokes you want the key to represent. The system will continue to act on these keystrokes as if key definition was not occurring. This enables you to monitor the key definition to ensure that you are actually creating a translation that will do what you wish. 4. When you have finished redefining the key press the alt = key again. The cursor will take on its normal shape and key definition is done. Unless saved in a disk file ('Saving Key Definitions'), the new key translation will be lost when the system is rebooted. For example, to define alt c as 'copy' follow these steps: 1. Press alt =, the cursor will change to block form. 2. Press alt c, the key you wish to define. 3. Type in 'copy'. 4. Press alt =, the cursor will change back to its normal shape. Now press alt c and watch 'copy' be returned. To undefine a key, merely define it without a definition (alt =, key, alt =). Space Considerations Newkey comes with enough translation space for 300 characters. If new key definitions total more than 300 characters in a session, Newkey will display this message in reverse video: *OUT OF MEMORY FOR DYNAMIC DEFINING - PRESS ESC TO CONTINUE* If you receive this message all further new key definition will be halted including the one you are in the middle of doing. At this point the only way to get new key definition space is to save the current key definitions and then reload them. This will reinitialize the 300 free spaces for further key definition (DOS 1.1 only, DOS 2.0 users will need to increase the size of the dynamic define area. Please refer to the special note in the 'LOAD FILE' section in the Newkey1 Overview.) Should you wish to have more than 300 free spaces at the beginning of the session refer to the parameters section in 'LOADING NEWKEY'. Backspace handling During key definition, Newkey treats the back cursor key as a back space and delete. This allows you to make correct a mistake during key definition without the correction becoming part of the key definition. SPECIAL KEY DEFINITION FEATURES Many of these features are illustrated in the key definition file, TEST.KEY described later. NESTED KEY TRANSLATION Newkey will translate keys within key definitions down to 8 levels. For example, assume the following keys have been defined as follows: alt 1 = level 1 alt 2 alt 2 = level 2 alt 3 alt 3 = level 3 alt 4 alt 4 = level 4 alt 5 alt 5 = level 5 alt 6 alt 6 = level 6 alt 7 alt 7 = level 7 alt 8 alt 8 = level 8 alt 9 alt 9 = level 9 alt 0 When alt 1 is pressed, Newkey will check each character returned ('L', 'e', 'v', 'e ', 'l',' ','1','alt 2') to see if they too have been defined and if so, will return their translation. Newkey will find that alt 2 has been defined and will check its definition for further translation to a depth of 8 levels. At the eighth level Newkey stops checking and returns that translation without further checking. So in this case, Newkey will return 'level 1level 2level 3level 4level 5level 6level 7level 8alt 9'. Translation continues to the eight level before it stops. Recursion If at any time newkey detects a recursive loop which would result in an infinite translation loop (a=b, b=c, c=a for example) it will display the following message in reverse video: RECURSION DETECTED - TRANSLATION ENDED - PRESS ESC TO CONTINUE Press the ESC key to continue. The key at which recursion was detected will be returned untranslated. TRANSLATION BYPASS Newkey provides the ability to prevent further translation within a key definition. If you have a character you wish to be returned without any further translation follow these steps: 1. Before entering the key, press ctrl 2. 2. Press the key you wish to always be returned. When Newkey encounters this key at this spot within the key definition it will return it without further translation even if the key is defined in the key definition file. For example, suppose you wished to define a key to be 'ctrl k ctrl d' but ctrl k was already defined as 'ctrl k ctrl q'. Follow these steps: 1. Press alt = to start key definition. 2. Press alt k, the key you wish to define. 3. Press ctrl 2 to signal that the next key is not to be translated. 4. Press ctrl k, the key you wish to be returned. 5. Press ctrl d 6. Press alt = to end key definition. Now when you press alt k, ctrl k, not 'ctrl k ctrl q', plus ctrl d will be returned. The no translate key only affects the next key entered. To prevent translation of subsequent keys it will be necessary to press the no translate key before entering each of them. Ctrl 2 may be changed to whatever you desire. Please refer to the section 'Modifying Newkey'. VARIABLE LENGTH FILL-IN-THE-BLANKS Newkey provides you with the ability to define variable length fill-in-the-blanks fields within key translations. When one of these is encountered in a key translation, Newkey will stop translation and wait for the user to enter any keystrokes he wishes. Newkey will continue to accept keystrokes until the return key is pressed when normal translation will continue. To define a variable length fill-in-the-blanks field follow these steps: 1. Press alt -. The cursor will change from a full block to half block with its bottom missing. 2. Enter whatever keystrokes you wish. 3. Press alt -. The cursor will change back to a full block. For example, suppose you frequently started a letter with 'My dear John (Frank, Susan, etc.) it is now time' you might wish to define one key to mean 'My dear xxxxxx it is now time.' To do this you would follow these steps: 1. Press alt = to start key definition. 2. Press alt l, the key you wish to define. 3. Type 'My dear '. 4. Press alt - to start variable length field definition. 5. Type in any name, although it is not necessary to the working of the key definition. 6. Press alt - to end variable length field definition. 7. Type in ' it is now time'. 8. Press alt = to end key definition. Now if you were to press alt l, 'My dear ' would be displayed and the system would wait for you to enter a name. Once you had entered a name and pressed the return key the system would continue with ' now is the time'. Alt - and the return key as terminator may be changed to whatever you desire. Please refer to the section 'Modifying Newkey'. FIXED LENGTH FILL-IN-THE-BLANKS Newkey provides you with the ability to define fixed length fill-in-the-blanks fields within key translations. When one of these is encountered in a key translation, Newkey will stop translation and wait for the user to enter a predefined number of keystrokes. Newkey will accept keystrokes until the predefined number is reached when normal translation will continue. To define a fixed length fill-in-the-blanks field follow these steps: 1. Press ctrl -. The cursor will change from a full block to half block with its top missing. 2. Enter whatever keystrokes you wish. 3. Press ctrl -. The cursor will change back to a full block. For example, suppose you frequently started a letter with 'Enclosed are the xx (some number) items per your request' you might wish to define one key to mean 'Enclosed are the xx items per your request.' To do this you would follow these steps: 1. Press alt = to start key definition. 2. Press alt l, the key you wish to define. 3. Type 'Enclosed are the '. 4. Press ctrl - to start fixed length field definition. 5. Type in any two digit number. 6. Press ctrl - to end fixed length field definition. 7. Type in ' items per your request'. 8. Press alt = to end key definition. Now if you were to press alt l, 'Enclosed are the 'would be displayed and the system would wait for you to enter any two characters. Once you had entered the second character the system would continue with ' items per your request.' Ctrl - may be changed to whatever you desire. Please refer to the section 'Modifying Newkey'. SPECIAL NEWKEY FEATURES Switching newkey off/on - CTRL 6 Newkey may be deactivated/activated by pressing ctrl 6. This acts as a toggle switching Newkey from one status to another. When deactivated Newkey is still resident in memory but it will act as if the normal keyboard interrupt is in control. Translation bypass - CTRL 2 Key translation may be bypassed by pressing ctrl 2 followed by the key desired. This is the same procedure used to enter a no translate key during key definition. .pa NEWKEY1 OVERVIEW Newkey1 provides many features to complement Newkey functions. INVOKING NEWKEY1 Newkey1 may be invoked in one of two ways: 1. Type Newkey1, press enter and a menu of options will be displayed. 2. Type Newkey1 plus a parameter and Newkey1 will perform the requested function and return to DOS. This option is particularly useful in a batch file invoked at system initialization. NEWKEY1 FUNCTIONS DISPLAY DIRECTORY (/d) Select function #1 on the menu screen or else type in 'newkey1 /d' and press enter. Newkey1 will display a directory of all keys that have been defined. DISPLAY TRANSLATION OF KEY (/k) Select function #2 on the menu screen or else type in 'newkey1 /k' and press enter. Newkey1 will display a screen requesting you to enter the key you wish translated. If the key has been defined to Newkey its translation will be displayed. The translation will be one character every five spaces and its end will be marked by a string of 'FFFF'. Each character will be described by a string 1 to 4 characters in length. For more information refer to 'Description of key translation display'. SAVE FILE (filename.ext/s) Select function #3 on the menu screen or else type in 'newkey1 file.key/s' and press enter. 'file.key' is the name of the key definition file in which you wish to save your current key definitions. It may be any legal file name. If you select function #3, another screen will be displayed requesting a file name. This function will save your current key definitions from memory in a disk file which may later be reloaded by Newkey1 into memory again. .pa LOAD FILE (filename.ext/l) Select function #4 on the menu screen or else type in 'newkey1 file.key/l' and press enter. 'file.key' is the name of the key definition file you wish to load into memory. If you select function #4, another screen will be displayed requesting a file name. This function will load the key definitions from a disk file into memory where they can be used by Newkey. Any previous key definitions in memory will be wiped out. *** SPECIAL NOTE TO DOS 2.0 USERS *** When I wrote the bulk of Newkey only DOS 1.1 was out and I made some basic design decisions designed to use a minimum amount of memory. One of these decisions involved loading the key definition file from a program external to the resident portion of Newkey and loading it right on top of the resident portion in contiguous storage. Naturally this works fine under DOS 1.1 but not DOS 2.0. DOS 2.0 places a piece of storage after each piece of storage made resident. It uses this to check for storage corruption, however it prevents the key definition file from being loaded on top of Newkey. Therefore, under DOS 2.0 the key definition file is only loaded if there is enough space in the dynamic define area (used for new key definitions) to hold the file's key definitions. If there is enough space, the key definitions are loaded and the remaining space used for the dynamic key definition area. If there is not enough space the message: FILE TOO BIG TO LOAD is displayed. If you receive this message it will be necessary to expand the dynamic define area either through the run time parameter (refer to parameter section in 'LOADING NEWKEY') or by actually modifying the code (refer to 'Modifying Newkey') to a size large enough to hold the file's key definitions plus whatever size you actually want the dynamic define area to be. To determine how much space must be reserved for a file's key definitions follow this procedure: 1. Determine the size of the key definition file (use 'dir filename.ext'). 2. Subtract 760 from this file size. This result is the number of bytes of key definitions which you need to reserve. 3. Divide by 2 to get the number of characters. 4. Add to this figure the number of characters you wish to reserve for the dynamic define area. 5. Re-boot. 6. Invoke the new version of Newkey setting the run time parameter appropriately. 7. Load the key definition file. MERGE FILE (filename.ext/m or filename.ext/m/o) This function will merge the key definitions from a disk file into memory where they can be used by Newkey. The previous key definitions in memory will be kept. If the same key is defined both in memory and in the merge file, the in-memory definition will be retained unless the overwrite option is specified. To merge, select function #5 on the menu screen or else type in 'newkey1 file.key/m' or 'newkey1 file.key/m/o' and press enter. 'file.key' is the name of the key definition file you wish to merge into memory. The second form, ending in '/o', will invoke the overwrite option. If you select function #5, another screen will be displayed requesting a file name and whether you want to use the overwrite option. The same DOS 2.0 space considerations apply to this function as to the load function described in the previous section. CLEAR CURRENT KEY DEFINITIONS (/c) Select function #6 on the menu screen or else type in 'newkey1 /c' and press enter. This function will clear all current key definitions from memory. SWITCH STATUS (/t) Select function #7 on the menu screen or else type in 'newkey1 /t' and press enter. This function will switch newkey's status from on to off or vice-versa. When Newkey's status is off, Newkey is still resident but permits no normal Newkey functions (translation, key definition) to occur. If invoked through the menu the current status is displayed. If invoked directly, Newkey1 will return a message indicating its current status after the switch. This function is equivalent to using ctrl 6 to switch Newkey's status. UNLOAD AND RECLAIM MEMORY (DOS 1.1 only) (/u) Select function #8 on the menu screen or else type in 'newkey1 /u' and press enter. This function will unload Newkey completely from the system and free up its memory for reuse. Caution must be exercised in using this feature. If another program has been permanently loaded after Newkey then its storage will also be freed. This function will only work under DOS 1.1. .pa MODIFYING NEWKEY Almost every key and parameter Newkey uses may be changed. The following should provide the information necessary to do this. All of these changes are done using Debug. Follow these steps: 1. Type in 'copy newkey.exe newkey.alt' and press enter. This will create an alternate version of newkey.exe. 2. Type in 'debug newkey.alt' and press enter. This will invoke debug and load Newkey.alt. 3. Next enter the modifications as described below. Note that when changing a keystroke it is necessary to change the scan code as well as the ascii code. 4. Before modifying Newkey first check that you are actually modifying the correct address by issuing a 'D address' command and checking the dumped data against what you expect to find. 5. If the dumped data agrees with what you expect to find then issue a 'F address l2 xx xx' where xxxx is the new data to be entered. 6. Repeat steps 3 and 4 until all desired changes have been made. 7. Type 'w' and press enter. This will write the changes to disk. 8. Type 'q' and press enter. This will end the debug session. 9. Type in 'ren newkey.exe newkey.old' and press enter. This will rename the old version of newkey. 10. Type in 'ren newkey.alt newkey.exe' and press enter. This will rename the new version of newkey. 11. Load your new version of Newkey and test the changes. (DOS 2.0 users will have to re-boot.) If problems develop, rename the new version back to newkey.alt, rename the old version back to newkey.exe and reload the old version. Then use debug to check your changes. MODIFICATIONS NOTE: The 8088 stores its data backwards, or in other words in reverse order when working with 2 byte fields. These modifications all involve changing 2 byte fields. Thus, once you have decided what you are going to change, enter the last byte first and the first byte last. For example, suppose that you are going to change the size of the dynamic define area from 300 characters to 256 characters. First determine the hex equivalent of 256, x'0100', reverse the '01' and '00' to get x'0001'. This is the order in which you would enter the change using debug. To modify the key codes you need to enter both the ascii code and the scan code. The first byte (displayed by debug) is the ascii code, the second, the scan code. These codes are documented in the IBM Technical Reference Manual. The 'current data' fields are listed in the order displayed by debug which is backwards due to 8088 processing as described above. FIELDS WHICH MAY BE MODIFIED Dynamic define area length - changing the amount of dynamic define area reserved for new key definitions. This figure should not exceed 13,500 decimal, '346c' hex. Address: 30d Current data: x'2c01' Be careful to reverse order Alt = - changing the define key initiator/terminator Function: To change the key used to begin and end the key definition process. Address: 38f Current data: x'0083' Be careful to reverse order Alt - - changing the Newkey variable length fill-in-the-blanks key initiator Function: To change the key used to begin and end the definition of the variable length fill-in-the-blanks fields during key definition. Address: 387 Current data: x'0082' Be careful to reverse order CR - changing the end of the variable fill-in-the-blanks terminator Function: To change the key used to end a variable length fill-in-the-blanks pause during key translation. Address: 38d Current data: x'0d1c' Be careful to reverse order Ctrl 6 - changing the Newkey toggle key Function: To change the key used to turn Newkey off and on. Address: 385 Current data: x'1e07' Be careful to reverse order Ctrl - - changing the Newkey fixed length fill-in-the-blanks key initiator Function: To change the key used to begin and end the definition of the fixed length fill-in-the-blanks fields during key definition. Address: 389 Current data: x'1f0c' Be careful to reverse order Ctrl 2 - changing the no translate key indicator Function: To change the key used to signal that the next key entered during key definition is not to be translated. Address: 38b Current data: x'0003' Be careful to reverse order DESCRIPTION OF KEY TRANSLATION DISPLAY The Newkey1 directory and key translation display use four character codes to describe characters. For the most part these codes are self explanatory, but if there is any confusion about their meaning the following should clarify matters. ^ - control prefix ~ - alt prefix \ - capitalization prefix F - followed by a number is a function key prefix SPECIAL CODE - DESCRIPTION CR - return key (Carraige Return) FILL - fixed length fill-in-the-blanks spot NOTR - 'no translate' character, indicates that next character will not be translated. PAUS - variable fill-in-the-blanks spot SPAC - space or blank ^END - control-end ^HOM - control-home ^PGD - control-pgdn ^PGU - control-pgup ^PSC - control-PrtSc ^<-- - control-<-- (cursor backwards) ^--> - control---> (cursor forwards) UNK - unknown character, could not translate. This should not happen. .pa SAMPLE KEY DEFINITION FILES Several sample key definition files are supplied with Newkey to illustrate its use and provide you with a starting point. These files are described below. There are a general set of DOS keys common to these files which are described at the end. ASM.KEY - Assembler programmer's customization file KEYS ACTION ---- ------ Alt a ';****.....****' (line of '*'s) Alt b 'byte ptr ' Alt o 'offset ' Alt w 'word ptr ' I use Wordstar to do my programming so that these commands are merged with my Wordstar file. In addition to these, I use F1 to set up my assembler environment under Wordstar. This involves mainly setting appropriate tab stops and I have left F1 set up to do this. DVORAK.KEY - Dvorak keyboard customization This file contains the key definitions necessary to redefine your keyboard to the Dvorak layout. There is one minor problem with using the Dvorak layout with the Caps Lock feature. Caps Lock will only lock the standard alphabet into shift mode. Since the Dvorak layout uses some non-alphabetic keys the Caps Lock feature will not automatically capitalize these keys, although normal shifting will. For more information about the Dvorak layout consult the article "Using IBM's Marvelous Keyboard" page 402 in the May 1983 issue of Byte magazine. The general DOS definitions are not part of this file. TEST.KEY - illustrates Newkey features KEY ACTION --- ------ F1 Illustrates the fixed length fill-in-the-blanks feature. F2 Illustrates the variable length fill-in-the-blanks feature. F3 Illustrates the no translate feature. Alt 1 Illustrates the nested definitions feature. Each key thru returns 'levelx' plus whatever the next higher alt number is defined as. These are defined as described in the Alt 9 'Nested key translation' section earlier in the text. WS.KEY - Wordstar customization file Newkey may be used to customize the Wordstar environment. F1 creates a customized initial environment. Many of the commands depend upon making sure that alt f is defined to be the active Wordstar file you are using. KEYS ACTION ---- ------ F1 Set help level to 0, toggle off justification, toggle off auto-hypenation F2 Save file (Ctrl KS), return to original cursor position (Ctrl QP), copy file (defined by alt f) to your a disk (Ctrl KO). This will save your current file as defined by alt f and then copy it to your a disk. This is a one step procedure Wordstar users on a ram disk can use to save their file on a floppy without leaving their current position within Wordstar. Alt F2 Save file and return to original cursor position. F5 Underscore Alt F5 Open underscore, accept input, close underscore after return key is struck. F6 Double strike Alt F6 Open double strike, accept input, close double strike after return key is struck. Alt F9 Address a short envelope and leave me at position to start receiver's address. Alt F10 Type my address and end at spot to enter date. Del Delete character directly above cursor. Alt d Call up Wordstar document file (d, alt f, return) Alt f Current file name. Used by F2, alt d, and alt n. Alt n Call up Wordstar non-document file (n, alt f, return) GENERAL DOS KEYS COMMON TO MOST KEY FILES: Alt c 'copy ' Alt e 'erase ' Alt f Current file name. Used in other key translations. Alt t 'dir ' INFORMATION ABOUT THE FILES ON THE NEWKEY DISK LOADNEW.BAT - This is a sample batch file which will load Newkey and the sample Wordstar key definition file, WS.KEY. NEWKEY.DOC - This is the documentation file which contains this document. It is only required when you want to print the documentation. NEWKEY.EXE - This is the program whick actually replaces IBM's keyboard interrupt (x'16). This program remains resident while other programs execute and unless called upon to translate will be transparent. NEWKEY1.EXE - This program provides several functions necessary to effectively use Newkey and is described further in this document. PRINTDOC.EXE - This program will print the document file, NEWKEY.DOC and is only needed for that purpose. All files ending in 'KEY' are sample key definition files and are described elsewhere in this document. .pa NEWKEY OVERVIEW NEWKEY REQUIREMENTS Newkey requires PC-DOS 1.1 OR 2.0 and will run on either a monochrome or color monitor. The base program requires approximately 3.7K of memory plus an additional 2 bytes per character of translation and reserved dynamic define area. HOW DOES NEWKEY WORK? The Newkey keyboard enhancer consists of two programs, Newkey.exe and Newkey1.exe. Newkey.exe, when invoked will replace the normal keyboard interrupt (x'16') of DOS. Just as the normal keyboard interrupt, Newkey will read the keyboard buffer and return the key to the requesting program, except that Newkey will first check the key against its key definition file (where the key translations are stored) and if it finds an entry for that key it will return the corresponding translation. Newkey1.exe, the companion program to newkey.exe, provides several functions necessary to use Newkey.exe effectively (as described in the 'Newkey1 Overview'. Newkey1 is loaded into high memory so that key definition files may be freely loaded. This raises a potential problem should there not be enough free space between the top of Newkey and the bottom of Newkey1 to load a key definition file. If this should happen results will be unpredictable. NEWKEY'S LIMITATIONS Newkey allows redefinition of any key (except ctrl break, ctrl 6, ctrl 2,and alt =). Newkey will handle up to approximately 27k of key definitions, but any key definition may be as long as you wish up to this maximum. The 27k maximum includes a few bytes for overhead and two bytes per character of translation. Results are unpredictable should the 27k maximum be exceeded. .pa TIPS ON USING NEWKEY USE YOUR AUTOEXEC.BAT FILE Put the commands to load Newkey and your key definition file in your autoexec.bat file. This will cause Newkey and your key definitions to be automatically loaded whenever you boot. If you have disks for different purposes, each disk could contain a copy of Newkey, Newkey1 and your key definition files. An example of the statements you would want to use can be found in LOADNEW.BAT, a batch file supplied with Newkey. Use your editor to copy these statements into your autoexec.bat file and change the parameters as appropriate. SETTING THE DYNAMIC DEFINE AREA SIZE PARAMETER When you first install Newkey you will be actively defining keys. This will require a lot more space in the dynamic define area than you will normally use. During these early sessions set the dynamic define area size parameter to a large number, 5000 for example. This will enable you to define key definitions using up to 5000 characters without running out of space. Later, when you have finished creating your key definition files, lower the number to a level which will support your normal key definition needs during a session. Newkey uses 300 as a default, but you can set the number as low as 5. Of course you may set the define area size at any level you wish, but remember, that area is not available to any other programs. DOS 2.0 users must also allow enough space to load their key definitions in addition to supporting their normal key definition needs during a session (see Special Note to DOS 2.0 Users in LOAD FILE section under NEWKEY1 FUNCTIONS.) The dynamic define area size parameter is specified when you load Newkey. For more information refer to the section Newkey Parameters under LOADING NEWKEY. DO NOT FORGET TO SAVE YOUR KEY DEFINITIONS Do not forget to save your key definitions at the end of a session. Unless you save the keys you have defined during the current session they will be lost when you re-boot or turn off the computer. It is suggested that as soon as you have finished defining a set of keys you wish to keep, that you save them immediately. It is very easy to start a session defining new keys, proceed to use them for the rest of the session, and then turn off the computer. If this happens, you will have to redefine each key again. For information on saving your key definitions refer to the SAVE FILE section under NEWKEY1 FUNCTIONS. COMBINING KEY DEFINITION FILES Occasionally you may wish to combine two key definition files. This may be done by loading one of the files into memory using the LOAD FILE function, merging the second into memory using the MERGE FILE function, and then saving the key definitions using the SAVE FILE function. These functions are described under NEWKEY1 FUNCTIONS. MULTIPLE KEY DEFINITION FILES You may wish to define multiple key definition files based on function. This would allow you to easily build different key definition files without redefining each function's keys for each key definition file. They could also be used to create in-memory key definitions at boot time without combining them all into one key definition file. For example, you could define a file for your word processor, speadsheet, general DOS commands, etc. and then merge various combinations of them together to create one file, or you could merge each file in at boot time. .pa DISCLAIMER. In no event will the author be liable to you for any damages, including any lost profits, lost savings or other incidental or consequential damages arising out of the use of or inability to use these programs, even if the author has been advised of the possibility of such damages, or for any claim by any other party. PERMISSION TO COPY: Individuals are granted permission by the author to freely copy the Newkey programs and documentation for their own use or to share with others, so long as no price or other consideration is charged. Computer clubs and other non-profit organizations are granted permission by the author to freely copy the Newkey programs and documentation and share it with their members, so long as: 1. No price or other consideration is charged. However, a distribution cost may be charged for the cost of the diskette, so long as it is not more than $10 total. 2. Club members are informed of the user-supported concept and encouraged to support it with their donations. 3. The programs and documentation are not modified in any way and are distributed together. Companies are granted permission by the author to copy the Newkey programs and documentation for use on other computers and at other locations in the company, so long as: 1. The full registration fee of $30 has been paid for the original copy of the program. 2. A usage fee of $25 is paid for each additional "building" where Newkey will be used. Within any building for which the usage fee has been paid, Newkey may be copied freely for use on any computer in that building. .pa THE USER-SUPPORTED CONCEPT. User-supported Software You are encouraged to copy and share this program with others. If after evaluating this program you find it to be useful, I trust you to send a $30 payment. Frank Bell 20950 Smallwood Birmingham, MI 48010 User-supported software is an experiment in distributing computer programs, based on these beliefs: 1. That the value and utility of software is best assessed by the user on his/her own system. 2. That the creation of personal computer software can and should be supported by the computing community. 3. That copying of programs should be encouraged, rather than restricted. Anyone may legally obtain an evaluation copy of the program from a friend or computer club. After you have had a chance to use and evaluate the program in your own environment, you are trusted to either forward a payment to the author, or to discontinue use of the program. In any case, you are encouraged to copy the program for evaluation by others. Free distribution of software and voluntary payment for its use eliminates costs for advertising and copy protection schemes. Users obtain quality software at greatly reduced cost. They can try it out before buying, and do so at their own pace and in the comfort of their own home or office. The best programs will survive, based purely on their quality and usefulness. Please join the experiment. If you believe in these ideals, your contribution is solicited to help make them work. PROBLEMS, SUGGESTIONS, ETC. If you should have any problems, suggestions or questions please feel free to write me at the above address. hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh